DLINK

 
 DLINK <options> <files> <libraries>

 Options may occur anywhere on the command lines.  Any file ending in
 .o[bj] is assumed to be an object file.  Any file ending in .l[ib] is
 assumed to be a library.  Any file name beginning with @ specifies a
 text file containing a further list of files.

 File ordering is maintained.  Section ordering is maintained.  All
 sections of the same name are coagulated together with ordering
 maintained.  EXCEPTION: inter-section ordering is not maintained
 within a library since library modules are random included.  However,
 ordering is maintained *between* libraries.

 All object files specified are included in the final executable.  All
 libraries specified are searched at the point they are specified (that is,
 specifying an object file that references a symbol defined in a library
 specified BEFORE the object file will cause an undefined symbol error).
 Normally an object file is specified after a library to terminate an
 autoinit or autoexit section.

 You do not have to order object files within a library, DLink will
 automatically make as many passes as required to handle all internal
 library references.  However, ordering object files will make DLink go
 faster.

 Symbols defined in object files overide symbols defined in libraries.
 Symbols defined in libraries specified before later libraries overide
 symbols defined in later libraries.  Symbols defined in a library and
 also defined in a later specified object module causes an error.


 CREATING A LIBRARY

 DLink libraries are standard Amiga libraries... simply join one or more
 object modules together and rename the result with a .lib extension.


 LINKER SYMBOLS AND A4 RELATIVE ADDRESSING

 DLink generates the following special symbols to aid in program
 startup:

 __ABSOLUTE_BAS  base of data in volatile space.  This symbol is NOT
         defined for normal residentable programs since the
         base address is not known (must be allocated run-time)

 __DATA_BAS      base of data in non-volatile space.  This symbol points
         to a read-only copy of the initialized data for a
         program.  For Non-residentable programs this is the
         same as __ABSOLUTE_BAS.

         For residentable programs this points to a read-only
         copy of the initialized data that the program can
         duplicate on startup.

         For programs linked with an absolute base address for
         data this points to the end of the CODE section.  The
         ROMABLE program always generates a ROM copy of the
         initialized data just after the CODE section (which
         startup code must copy into RAM)

 __DATA_LEN      Length of data space is LONGWORDS.  I.E. __DATA_LEN * 4
         yields the number of bytes of initialized data.  This
         is used by startup code to copy read-only initialized
         data to volatile space (residentable and data-absolute
         programs)

 __BSS_LEN       Length of bss space in LONGWORDS.  I.E. __BSS_LEN * 4
         yields the number of bytes of uninitialized (BSS) data.
         This is used in combination with __DATA_LEN to allocate
         the DATA+BSS space for residentable programs, and clear
         the BSS space for non-residentable and absolute-
         data-base programs.

         The BSS space occurs after the DATA space unless the
         -frag option is used.

 __RESIDENT      This symbol is set to 0 if the -r option was used and
         1 if the -r option was not used.  If set to 1 (-r
         option), then NO BSS SPACE IS PREALLOCATED WHEN THE
         PROGRAM IS RUN.  The startup code must allocate DATA+BSS
         space, copy read-only initialized data over to this
         space, and clear out the BSS portion before it the
         program can run.

         Programs linked with the -mw or -ma options obviously
         do not 'allocate' their data space since it is
         predefined.  Most Amiga programmers will never use
         the -mw or -ma options, by the way.


 SMALL DATA MODEL

 The small data model uses A4 relative addressing.  The linker sets up
 all relative offsets such that A4 must be initialized by startup code
 the BaseOfInitializedData + 32766 for A4-relative references to access
 the appropriate address.


 RESIDENT

 If the -r options is given then NO BSS SPACE is allocated after the
 data space... the startup code MUST allocate a data+bss space as shown
 above.  DLink will give error messages for any absolute data references
 that occur (except the __DATA_BAS symbol which must be used to copy the
 static data to the newly allocated data+bss memory on program startup).

 DLink will give an error message if any data-data reloco32s exist when
 you specify the -r option as such relocations would be incorrect when
 copied to the newly allocated data+bss space.  DC1 understands this and
 will produce autoinit code to handle any such static data relocations
 that occur in your C code when the -r option is given to compile a C
 program.

 However, DLink does allow data-data relocations to occur if an absolute
 data base is specified along with the -r option.  This is used only
 when making ROMABLE code.


 PC-RELATIVE

 Because the linker will insert a jump table for PC-RELATIVE references
 to different hunks (after coagulation) or where the range is larger
 than +/-32K, data should not be placed into a code segment and be
 referenced via an external label(pc) unless you are positive the
 reference is within +/-32K.  This can only happen when referencing
 between like-named code hunks.  NOTE that the jump table is tagged
 onto the end of the section the jump(s) occur in and thus you do
 not want to have any autoinit/autoexit code that might possibly
 generate a jump table (since the whole idea with autoinit is that
 the code falls through to other autoinit code until the terminating
 section in x.o's RTS).

 Currently dlink cannot handle inter-module PC-RELATIVE references
 beyond +/-32K (i.e. when one object file has more than 32K of code).
 An error will occur.

 Note that if -frag is used you cannot make PC-RELATIVE calls
 between sections of differing names ever, or make a program resident.
 The -frag option is almost never used on untested.


 OVERLAYS (NOT SUPPORTED)

 Overlays are not supported as yet, but i am sure they will be one day
 soon. MF


 OPTIONS

 Options:

 -o execname     name of executable

 -s          Include symbolic information.  NOTE, if -r is used
         symbolic info for the data sections will point to
         the statically init'd stuff, NOT The actual data
         space (in BSS) referenced by the code.  This is a bug.

 -frag       Fragment output file (default is to coagulate all
         hunks of the same type regardless of name).  If
         frag is specified then only hunks of the same type
         AND name are coagulated.

         see fragmentation note at bottom

 -r[es]      Resident link.

 -pi         Position independant non-residentable (i.e. only
         one copy of the data but also no relocation hunks)

 -pr         residentable position independant

 -P<postfix>     specify library name postfix.  If DLink cannot find
         the library as specified it will append the postfix
         and try again.  Used by DCC to specify the memory
         model.

 -mw addr        specify absolute data base
 -ma addr        specify absolute data base

         Both options do exactly the same thing and are in
         duplicate to conform to DCC's options.

         -mw/-ma specify the base of data as a decimal,
         0octal, or 0xHEX address.  You must use the -r
         option in conjunction with these options.

         DLink will resolve all Absolute-Word addresses
         but not all Absolute-Long addresses.  This is left
         up to the ROMABLE program which generates a raw
         binary image of the program that can then be
         transfered to an EPROM.

         DO NOT USE WHEN GENERATING AMIGA EXECUTABLES

 -d[#]       debug mode (spews lots of debugging junk out)

 -E file     specify stderr file, any errors are appended to the file
         instead of to stdout.  Useful for batch compiles

 -chip       chip-only - forces all hunks into CHIP memory

 -L0         remove default library search path, including all
         explicitly specified (-L dir) directories up to
         this point.

 -L dir      add the specified directory to the library search
         path.  If the object module or library can not be
         found in the current directory, directories
         specified with -L are searched.  -L directories are
         searched before the default library directory
         (DLIB:), assuming it was not removed with -L0 .

         Note that the directory path specified by -L is used to
         search for libraries AND object modules.

         A trailing '/' is optional

 -P<postfix>     This allows you to specify -lc -Ps and DLink will
         automatically look for cs.lib ... you can specify a
         postfix that occurs before the '.lib' in the
         library name here.  If DLink cannot find the
         library as it is named by default it will try
         it with the postfix.

         DCC uses this to supply the memory model to DLINK
         also allowing the user to say '-lm' in DCC and have
         it find MS.LIB if you are using the small-data
         model.


 SPECIAL NOTE ON FRAGMENTATION

 When -frag is specified, the linker will not create a special
 combined data+bss hunk (so data and bss can both be referenced with
 one base variable).

 However, when -frag is NOT specified, the linker will stil not
 necessarily combine ALL data hunks into one big hunk and ALL bss
 hunks into one big hunk.  Any data or bss hunk with special upper
 bits set (e.g. to force it into chip) is not combined into these
 special hunks, and any data or bss hunk whos NAME begins with
 'far' (upper or lower case) will also not be considered.


 EXAMPLE

 This is what DCC gives the linker to link the program 'foo.c' :

 dlink dlib:c.o @tmp dlib:x.o -o ram:foo

 --- tmp ---
 foo.o
 dlib:c.lib dlib:amiga.lib dlib:auto.lib
 -----------

 Basically it tells dlink to link the startup code, c.o, then the
 program object module(s) (foo.o), then c.lib, amiga.lib, and auto.lib,
 then finally x.o.

 DCC handles all this for you

 auto.lib contains autoinit code for certain selected libraries,
 including the dos.library.  Autoinit code is brought in whenever a
 given library base symbol has been referenced BUT NOT DEFINED. auto.lib
 defines the symbol and generates autoinit code to open the library and
 autoexit code to close the library.  To maintain portability you
 probably do not want to use this automatic library-openning feature
 yourself, it is really meant to support certain actions of the DICE
 library (such as floating point support).

 x.o terminates the autoinit and autoexit sections with an RTS. The
  autoinit and autoexit sections are called from the startup code c.o .